<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<!-- HTML file produced from file: manual.tex --
 -- using Hyperlatex v 2.3.1 (c) Otfried Cheong--
 -- on Emacs 21.4 (patch 15) "Security Through Obscurity" XEmacs Lucid, Fri Dec  3 20:36:15 2004 -->
<HEAD>
<TITLE>Scheme 48 Manual -- The configuration language</TITLE>

</HEAD><BODY BGCOLOR="#ffffff">
<EM>Scheme 48 Manual</EM> | <A HREF="s48manual.html#top_node">Contents</A> | In Chapter: <A HREF="s48manual_24.html">Module system</A><BR>Previous: <A HREF="s48manual_25.html">Introduction</A> | Next: <A HREF="s48manual_27.html">Interfaces</A>
<H2>The configuration language</H2>
The configuration language consists of top-level defining forms for
 modules and interfaces.
Its syntax is as follows:
<P><P><P><TABLE CELLSPACING="1" CELLPADDING="0"><TR>
<TD NOWRAP COLSPAN="1" ALIGN="LEFT">
   <I>&lt;</I>configuration<I>&gt;</I> </TD><TD NOWRAP COLSPAN="99" ALIGN="LEFT"><CODE>-&gt;</CODE>&nbsp;<I>&lt;</I>definition<I>&gt;</I><I><sup>*</sup></I> </TD></TR>
<TR>
<TD NOWRAP COLSPAN="1" ALIGN="LEFT"><I>&lt;</I>definition<I>&gt;</I> </TD><TD NOWRAP COLSPAN="99" ALIGN="LEFT"><CODE>-&gt;</CODE>&nbsp;
      <TT>(define-structure <I>&lt;</I>name<I>&gt;</I> <I>&lt;</I>interface<I>&gt;</I>
          <I>&lt;</I>clause<I>&gt;</I><I><sup>*</sup></I>) </TD></TR>
<TR>
<TD NOWRAP COLSPAN="1" ALIGN="LEFT"></TD><TD NOWRAP COLSPAN="99" ALIGN="LEFT"><CODE>-&gt;</CODE>&nbsp; <TT>(define-structures ((<I>&lt;</I>name<I>&gt;</I> <I>&lt;</I>interface<I>&gt;</I>)<I><sup>*</sup></I>)
          <I>&lt;</I>clause<I>&gt;</I><I><sup>*</sup></I>) </TD></TR>
<TR>
<TD NOWRAP COLSPAN="1" ALIGN="LEFT"></TD><TD NOWRAP COLSPAN="99" ALIGN="LEFT"><CODE>-&gt;</CODE>&nbsp; <TT>(define-interface <I>&lt;</I>name<I>&gt;</I> <I>&lt;</I>interface<I>&gt;</I>) </TD></TR>
<TR>
<TD NOWRAP COLSPAN="1" ALIGN="LEFT"></TD><TD NOWRAP COLSPAN="99" ALIGN="LEFT"><CODE>-&gt;</CODE>&nbsp; <TT>(define-syntax <I>&lt;</I>name<I>&gt;</I> <I>&lt;</I>transformer-spec<I>&gt;</I>) </TD></TR>
<TR>
<TD NOWRAP COLSPAN="1" ALIGN="LEFT"><I>&lt;</I>clause<I>&gt;</I> </TD><TD NOWRAP COLSPAN="99" ALIGN="LEFT"><CODE>-&gt;</CODE>&nbsp; <TT>(open <I>&lt;</I>structure<I>&gt;</I><I><sup>*</sup></I>) </TD></TR>
<TR>
<TD NOWRAP COLSPAN="1" ALIGN="LEFT"></TD><TD NOWRAP COLSPAN="99" ALIGN="LEFT"><CODE>-&gt;</CODE>&nbsp; <TT>(access <I>&lt;</I>name<I>&gt;</I><I><sup>*</sup></I>) </TD></TR>
<TR>
<TD NOWRAP COLSPAN="1" ALIGN="LEFT"></TD><TD NOWRAP COLSPAN="99" ALIGN="LEFT"><CODE>-&gt;</CODE>&nbsp; <TT>(begin <I>&lt;</I>program<I>&gt;</I>) </TD></TR>
<TR>
<TD NOWRAP COLSPAN="1" ALIGN="LEFT"></TD><TD NOWRAP COLSPAN="99" ALIGN="LEFT"><CODE>-&gt;</CODE>&nbsp; <TT>(files <I>&lt;</I>filespec<I>&gt;</I><I><sup>*</sup></I>) </TD></TR>
<TR>
<TD NOWRAP COLSPAN="1" ALIGN="LEFT"></TD><TD NOWRAP COLSPAN="99" ALIGN="LEFT"><CODE>-&gt;</CODE>&nbsp; <TT>(optimize <I>&lt;</I>optimize-spec<I>&gt;</I><I><sup>*</sup></I>) </TD></TR>
<TR>
<TD NOWRAP COLSPAN="1" ALIGN="LEFT"></TD><TD NOWRAP COLSPAN="99" ALIGN="LEFT"><CODE>-&gt;</CODE>&nbsp; <TT>(for-syntax <I>&lt;</I>clause<I>&gt;</I><I><sup>*</sup></I>) </TD></TR>
<TR>
<TD NOWRAP COLSPAN="1" ALIGN="LEFT"><I>&lt;</I>interface<I>&gt;</I> </TD><TD NOWRAP COLSPAN="99" ALIGN="LEFT"><CODE>-&gt;</CODE>&nbsp; <TT>(export <I>&lt;</I>item<I>&gt;</I><I><sup>*</sup></I>) </TD></TR>
<TR>
<TD NOWRAP COLSPAN="1" ALIGN="LEFT"></TD><TD NOWRAP COLSPAN="99" ALIGN="LEFT"><CODE>-&gt;</CODE>&nbsp; <I>&lt;</I>name<I>&gt;</I> </TD></TR>
<TR>
<TD NOWRAP COLSPAN="1" ALIGN="LEFT"></TD><TD NOWRAP COLSPAN="99" ALIGN="LEFT"><CODE>-&gt;</CODE>&nbsp; <TT>(compound-interface <I>&lt;</I>interface<I>&gt;</I><I><sup>*</sup></I>) </TD></TR>
<TR>
<TD NOWRAP COLSPAN="1" ALIGN="LEFT"><I>&lt;</I>item<I>&gt;</I> </TD><TD NOWRAP COLSPAN="99" ALIGN="LEFT"><CODE>-&gt;</CODE>&nbsp; <I>&lt;</I>name<I>&gt;</I> </TD></TR>
<TR>
<TD NOWRAP COLSPAN="1" ALIGN="LEFT"></TD><TD NOWRAP COLSPAN="99" ALIGN="LEFT"><CODE>-&gt;</CODE>&nbsp; <TT>(<I>&lt;</I>name<I>&gt;</I> <I>&lt;</I>type<I>&gt;</I>) </TD></TR>
<TR>
<TD NOWRAP COLSPAN="1" ALIGN="LEFT"></TD><TD NOWRAP COLSPAN="99" ALIGN="LEFT"><CODE>-&gt;</CODE>&nbsp; <TT>((<I>&lt;</I>name<I>&gt;</I><I><sup>*</sup></I>) <I>&lt;</I>type<I>&gt;</I>) </TD></TR>
<TR>
<TD NOWRAP COLSPAN="1" ALIGN="LEFT"><I>&lt;</I>structure<I>&gt;</I> </TD><TD NOWRAP COLSPAN="99" ALIGN="LEFT"><CODE>-&gt;</CODE>&nbsp; <I>&lt;</I>name<I>&gt;</I> </TD></TR>
<TR>
<TD NOWRAP COLSPAN="1" ALIGN="LEFT"></TD><TD NOWRAP COLSPAN="99" ALIGN="LEFT"><CODE>-&gt;</CODE>&nbsp; <TT>(modify <I>&lt;</I>structure<I>&gt;</I> <I>&lt;</I>modifier<I>&gt;</I><I><sup>*</sup></I>) </TD></TR>
<TR>
<TD NOWRAP COLSPAN="1" ALIGN="LEFT"></TD><TD NOWRAP COLSPAN="99" ALIGN="LEFT"><CODE>-&gt;</CODE>&nbsp; <TT>(subset <I>&lt;</I>structure<I>&gt;</I> (<I>&lt;</I>name<I>&gt;</I><I><sup>*</sup></I>)) </TD></TR>
<TR>
<TD NOWRAP COLSPAN="1" ALIGN="LEFT"></TD><TD NOWRAP COLSPAN="99" ALIGN="LEFT"><CODE>-&gt;</CODE>&nbsp; <TT>(with-prefix <I>&lt;</I>structure<I>&gt;</I> <I>&lt;</I>name<I>&gt;</I>) </TD></TR>
<TR>
<TD NOWRAP COLSPAN="1" ALIGN="LEFT"><I>&lt;</I>modifier<I>&gt;</I> </TD><TD NOWRAP COLSPAN="99" ALIGN="LEFT"><CODE>-&gt;</CODE>&nbsp; <TT>(expose <I>&lt;</I>name<I>&gt;</I><I><sup>*</sup></I>) </TD></TR>
<TR>
<TD NOWRAP COLSPAN="1" ALIGN="LEFT"></TD><TD NOWRAP COLSPAN="99" ALIGN="LEFT"><CODE>-&gt;</CODE>&nbsp; <TT>(hide <I>&lt;</I>name<I>&gt;</I><I><sup>*</sup></I>) </TD></TR>
<TR>
<TD NOWRAP COLSPAN="1" ALIGN="LEFT"></TD><TD NOWRAP COLSPAN="99" ALIGN="LEFT"><CODE>-&gt;</CODE>&nbsp; <TT>(rename (<I>&lt;</I>name<I>&gt;</I><I><sub>0</sub></I> <I>&lt;</I>name<I>&gt;</I><I><sub>1</sub></I>)<I><sup>*</sup></I>) </TD></TR>
<TR>
<TD NOWRAP COLSPAN="1" ALIGN="LEFT"></TD><TD NOWRAP COLSPAN="99" ALIGN="LEFT"><CODE>-&gt;</CODE>&nbsp; <TT>(alias (<I>&lt;</I>name<I>&gt;</I><I><sub>0</sub></I> <I>&lt;</I>name<I>&gt;</I><I><sub>1</sub></I>)<I><sup>*</sup></I>) </TD></TR>
<TR>
<TD NOWRAP COLSPAN="1" ALIGN="LEFT"></TD><TD NOWRAP COLSPAN="99" ALIGN="LEFT"><CODE>-&gt;</CODE>&nbsp; <TT>(prefix <I>&lt;</I>name<I>&gt;</I>) </TD></TR>
<TR>
<TD NOWRAP COLSPAN="99" ALIGN="LEFT"></TT></TT></TT></TT></TT></TT></TT></TT></TT></TT></TT></TT></TT></TT></TT></TT></TT></TT></TT></TT></TT></TT></TD></TR></TABLE>

<CENTER>The configuration language.</CENTER>
<P><A NAME="module-language-figure">&nbsp;</A>
<P>A <A NAME="2">&nbsp;</A><CODE>define-structure</CODE> form introduces a binding of a name to a
structure.  A structure is a view on an underlying package which is
created according to the clauses of the <TT>define-structure</TT> form.
Each structure has an interface that specifies which bindings in the
structure's underlying package can be seen via that structure in other
packages.
<P>An <TT>open</TT> clause specifies which structures will be opened up for
 use inside the new package.
At least one structure must be specified or else it will be impossible to
 write any useful programs inside the package, since <TT>define</TT>,
 <TT>lambda</TT>, <TT>cons</TT>, etc. will be unavailable.
Packages typically include <TT>scheme</TT>, which exports all bindings
 appropriate to Revised<I><sup>5</sup></I> Scheme, in an <TT>open</TT> clause.
For building structures that export structures, there is a <TT>defpackage</TT>
 package that exports the operators of the configuration language.
Many other structures, such as record and hash table facilities, are also
 available in the Scheme&nbsp;48 implementation.
<P>The <A NAME="3">&nbsp;</A><CODE>modify</CODE>, <A NAME="4">&nbsp;</A><CODE>subset</CODE>, and
 <A NAME="5">&nbsp;</A><CODE>prefix</CODE> forms produce new
 views on existing structures by renaming or hiding exported names.
<CODE>Subset</CODE> returns a new structure that exports only the listed names
 from its <I>&lt;</I>structure<I>&gt;</I> argument.
<CODE>With-prefix</CODE> returns a new structure that adds <I>&lt;</I>prefix<I>&gt;</I>
 to each of the names exported by the <I>&lt;</I>structure<I>&gt;</I> argument.
For example, if structure <CODE>s</CODE> exports <CODE>a</CODE> and <CODE>b</CODE>,
 then
<BLOCKQUOTE><PRE>
(subset s (a))
</PRE></BLOCKQUOTE>
exports only <CODE>a</CODE> and
<BLOCKQUOTE><PRE>
(with-prefix s p/)
</PRE></BLOCKQUOTE>
exports <CODE>a</CODE> as <CODE>p/a</CODE> and <CODE>b</CODE> as <CODE>p/b</CODE>.
<P>Both <CODE>subset</CODE> and <CODE>with-prefix</CODE> are simple macros that
 expand into uses of <CODE>modify</CODE>, a more general renaming form.
In a <CODE>modify</CODE> structure specification the <I>&lt;</I>command<I>&gt;</I>s are applied to
 the names exported
 by <I>&lt;</I>structure<I>&gt;</I> to produce a new set of names for the <I>&lt;</I>structure<I>&gt;</I>'s
 bindings.
<CODE>Expose</CODE> makes only the listed names visible.
<CODE>Hide</CODE> makes all but the listed names visible.
<CODE>Rename</CODE> makes each <I>&lt;</I>name<I>&gt;</I><I><sub>0</sub></I> visible as <I>&lt;</I>name<I>&gt;</I><I><sub>1</sub></I> 
 name and not visible as <I>&lt;</I>name<I>&gt;</I><I><sub>0</sub></I> , while
 <CODE>alias</CODE> makes each <I>&lt;</I>name<I>&gt;</I><I><sub>0</sub></I> visible as both <I>&lt;</I>name<I>&gt;</I><I><sub>0</sub></I> 
 and <I>&lt;</I>name<I>&gt;</I><I><sub>1</sub></I>.
<CODE>Prefix</CODE> adds <I>&lt;</I>name<I>&gt;</I> to the beginning of each exported name.
The modifiers are applied from right to left.  Thus
<BLOCKQUOTE><PRE>
(modify scheme (prefix foo/) (rename (car bus))))
</PRE></BLOCKQUOTE>
makes <CODE>car</CODE> available as <CODE>foo/bus</CODE>..
<P>The package's body is specified by <TT>begin</TT> and/or <TT>files</TT>
clauses.  <TT>begin</TT> and <TT>files</TT> have the same semantics, except
that for <TT>begin</TT> the text is given directly in the package
definition, while for <TT>files</TT> the text is stored somewhere in the
file system.  The body consists of a Scheme program, that is, a
sequence of definitions and expressions to be evaluated in order.  In
practice, we always use <TT>files</TT> in preference to <TT>begin</TT>; <TT>begin</TT> exists mainly for expository purposes.
<P>A name's imported binding may be lexically overridden or <EM>shadowed</EM>
by defining the name using a defining form such as <TT>define</TT>
or <TT>define-syntax</TT>.  This will create a new binding without having
any effect on the binding in the opened package.  For example, one can
do <TT>(define car 'chevy)</TT> without affecting the binding of the name
<TT>car</TT> in the <TT>scheme</TT> package.
<P>Assignments (using <TT>set!</TT>) to imported and undefined variables
are not allowed.  In order to <TT>set!</TT> a top-level variable, the
package body must contain a <TT>define</TT> form defining that variable.
Applied to bindings from the <TT>scheme</TT> structure, this restriction
is compatible with the requirements of the Revised<I><sup>5</sup></I> Scheme report.
<P>It is an error for two of a package's opened structures to export two
different bindings for the same name.  However, the current
implementation does not check for this situation; a name's binding is
always taken from the structure that is listed first within the <TT>open</TT> clause.  This may be fixed in the future.
<P>File names in a <TT>files</TT> clause can be symbols, strings, or lists
(Maclisp-style "namelists").  A "<TT>.scm</TT>" file type suffix is
assumed.  Symbols are converted to file names by converting to upper
or lower case as appropriate for the host operating system.  A
namelist is an operating-system-independent way to specify a file
obtained from a subdirectory.  For example, the namelist <TT>(rts
record)</TT> specifies the file <TT>record.scm</TT> in the <TT>rts</TT>
subdirectory.
<P>If the <TT>define-structure</TT> form was itself obtained from a file,
then file names in <TT>files</TT> clauses are interpreted relative to the
directory in which the file containing the <TT>define-structure</TT> form
was found.  You can't at present put an absolute path name in the <TT>files</TT> list.
<P><P>
  
Previous: <A HREF="s48manual_25.html">Introduction</A> | Next: <A HREF="s48manual_27.html">Interfaces</A></BODY></HTML>
